Skip to content

fix(cli): preserve quota guard diagnostics in Markdown - #9112

Merged
loopx-agent merged 2 commits into
mainfrom
codex/preserve-quota-guard-markdown-diagnostics-20261120
Nov 21, 2026
Merged

loopx-agent merged 2 commits into
mainfrom
codex/preserve-quota-guard-markdown-diagnostics-20261120

Conversation

@loopx-agent

@loopx-agent loopx-agent commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

A failed quota should-run can print # LoopX Turn Envelope even when permission denial or interrupted composition prevented an envelope from being produced. The Markdown dispatcher selected the renderer solely from the command name, making the diagnostic look like an admitted turn.

Route incomplete failures to a command diagnostic that retains the entire structured payload, including recovery instructions, original receipts and capture references. A genuine composed refusal keeps its Turn Envelope. Extract the existing JSON block formatting into the shared presentation helper used by both renderers. JSON output and the typed admission/settlement owners keep their existing behavior.

Validation at 3aece4651e6a5b89699f6be554c493ad1d0eb5dc

  • Reproduced two existing permission-error Markdown failures and two File/SQLite composition-error failures before the fix.
  • 112 permission and capture tests passed, including the original receipt/digest and no-duplicate-admission checks. The first full run had two subprocess source-discovery failures; both passed when their repository-external child processes explicitly received the source checkout through PYTHONPATH.
  • 48 presentation, protocol-history and envelope-budget tests passed.
  • Real CLI base/head validation-error comparison preserves all payload fields after checking and normalizing per-invocation rollout event ID/time. The Markdown diagnostic grows by 18 bytes for the command heading and explicit failure indicator.
  • Ruff, diff hygiene, public-safe outbound scan and bilingual RFC diff check passed.
  • Standard premerge passed, including all 10 catalog canaries, all 8 risk-profile smokes, Python compilation and direct hygiene checks. The CLI output budget/base-head differential is included. Independent review and merge qualification remain outstanding.

The bounded refactor shares the existing JSON block formatter across two real callers. This change is confined to CLI Markdown presentation and adds no state vocabulary, admission policy, scheduler change or runtime execution path. The reusable self-repair pattern now covers the mislabeling regression while retaining its existing recovery obligations.

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · Gemini · Google DeepMind · self_reported

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

已针对 PR #9112 exact head 3aece4651e6a5b89699f6be554c493ad1d0eb5dc 完成完整审查与本地验证(审查结论:APPROVE,无 P0/P1/P2 阻塞问题;PR 保持 OPEN,不执行合并)。

动机 / Motivation

受影响调用方与维护者:通过 loopx --format markdown quota should-run 消费配额守卫输出的代理宿主、CLI 操作者与排障人员。

修改前与修改后场景:在合入基线 8e9a28a 上,_quota_renderer 仅凭 command == 'should-run' 返回 render_turn_context_markdown,导致宿主机权限拒绝、参数校验失败、状态收集异常或 compose_turn_decision 中断时,Markdown 仍打印 # LoopX Turn Envelope 误导标题;修改后(3aece4651e),上述未完成失败改为输出 # LoopX Quota Should Run 与 - ok: False 并完整保留全部 JSON 恢复载荷,而已组合的 loopx_turn_envelope_v1 合规拒绝仍保持 # LoopX Turn Envelope。

可观测改善与边界:实测 base/head 真实 CLI 失败输出已从 # LoopX Turn Envelope 切换为 # LoopX Quota Should Run 并完整保留全部 14 个恢复 JSON 字段,权限拒绝、file/sqlite 组合中断及已组合拒绝单测全部通过。 本切片仅修正 CLI Markdown 展示分派并共享 JSON 块格式化辅助,不修改 JSON 输出、配额准入策略、持久化格式,也不负责修复 tests/control_plane/test_cli_output_budget.py 中既有主干旧断言。 若不修复,失败诊断在 Markdown 通道将继续伪装为 Turn Envelope,误导宿主机恢复与自修复排障。

改动思路 / Approach

入口与权威边界:所有配额策略与 Turn Envelope 组合仍由 TypeScript 控制面(compose_turn_decision)及 Python 失败报告器(quota_failure_report.py)决定;quota_result_delivery.py 在 emit_quota_result、captured_quota_failure_view 与末尾输出路径统一通过 failure=True 或 failure=not succeeded 调用 _quota_renderer(args, failure=...)。

核心设计取舍:将 JSON 对象块格式化收敛到共享辅助函数 render_json_object_block,并仅在 quota_presentation._quota_renderer 的 failure=True 分支依据 COMPLETE_TURN_DECISION_VERSION 分流诊断渲染,不改变 TypeScript 决策与失败报告所有权。 本次没有重复实现第二份 JSON 块序列化代码,而是把原内联在 turn_envelope_markdown.py 的 JSON 对象逐字段渲染逻辑提取到共享展示辅助模块 loopx/presentation/markdown.py 的 render_json_object_block,供 render_turn_context_markdown 与新增的 render_quota_guard_diagnostic_markdown 共同复用;同时也未复用有损字段裁剪的 render_quota_should_run_markdown(该渲染器不会输出 error_code、heartbeat_receipt、captured_decision 等恢复关键字段)。

当前 PR 边界与失败语义:仅调整 quota should-run 在 failure=True 下的 Markdown 渲染分派、抽提共享 JSON 块渲染辅助并更新 self-repair 参考条目;不修改 JSON 输出、配额策略或 ok=True 分支。 当 ok=True(failure=False)或失败载荷具备 schema_version == "loopx_turn_envelope_v1" 时,Markdown 路径与基准完全一致;当 failure=True 且无 loopx_turn_envelope_v1 时,渲染 # LoopX Quota Should Run 诊断并原样保留全部失败与恢复字段。

具体改动 / Changes

本 PR 共修改 7 个文件(+62/-18,净增 44 行),无新增独立 RFC 或外部书面规格(spec_basis = no_spec:本次修复对照既有配额失败恢复保真与 Markdown 展示分派契约,不涉及外部规范编号或持久化 schema 变更)。

  1. loopx/presentation/markdown.py(+10 / -0,生产代码):新增共享 render_json_object_block(payload),统一生成带换行字段分隔的 fenced JSON 代码块。
  2. loopx/presentation/renderers/turn_envelope_markdown.py(+1 / -6,导入 +2/-0,生产代码):render_turn_context_markdown 改为复用 render_json_object_block(payload),保持 # LoopX Turn Envelope 字节级等价输出。
  3. loopx/presentation/renderers/quota_event_markdown.py(+8 / -1,生产代码):新增 render_quota_guard_diagnostic_markdown(payload),输出 # LoopX Quota Should Run\n\n- ok: {payload.get('ok')}\n\n 后接完整 render_json_object_block(payload)。
  4. loopx/cli_commands/quota_presentation.py(+10 / -1,生产代码):在 _quota_renderer 的 command == "should-run" 分支中区分 failure,仅在 failure=True 时通过 render_failed_guard 检查 payload.get("schema_version") == COMPLETE_TURN_DECISION_VERSION 后决定沿用 render_turn_context_markdown 还是切换为 render_quota_guard_diagnostic_markdown。
  5. skills/loopx-self-repair/references/repair-patterns.md(+1 / -1,按需加载的参考文档):更新 quota_failure_presentation_runtime_reentry 模式行,补充 quota should-run 未完成失败在 Markdown 中不得误标为 Turn Envelope 的自修复记录。
  6. tests/control_plane/test_effect_runtime_host_permission.py 与 tests/control_plane/test_quota_decision_capture.py(+30 / -8,测试):覆盖宿主机权限拒绝、已组合拒绝保留 Turn Envelope,以及 file/sqlite 后端下组合中断失败在 Markdown 通道的诊断头与完整恢复字段断言。

关键代码讲解

  • _quota_renderer(loopx/cli_commands/quota_presentation.py:74-113):由 quota_result_delivery.py 的多处结果输出点调用。修改前 command == "should-run" 直接返回 render_turn_context_markdown;修改后当 failure=False 仍直接返回 render_turn_context_markdown,当 failure=True 时返回闭包 render_failed_guard,以 COMPLETE_TURN_DECISION_VERSION("loopx_turn_envelope_v1")作为唯一分流凭据,确保未形成完整 Turn Envelope 的权限拒绝、参数校验失败、收集失败与传输失败均路由至诊断渲染器,而其他配额子命令映射保持不变。
  • render_quota_guard_diagnostic_markdown 与 render_json_object_block(loopx/presentation/renderers/quota_event_markdown.py:10-14、loopx/presentation/markdown.py:42-48):从 turn_envelope_markdown.py 抽离的 render_json_object_block 原样序列化字典每一项为紧凑 JSON 行并保留键顺序,render_quota_guard_diagnostic_markdown 在其前方补充 # LoopX Quota Should Run 与 - ok: ...``,既修正误导性标题又避免 render_quota_should_run_markdown 丢失 `error_code`、`heartbeat_receipt`、`captured_decision` 等恢复载荷。
  • render_turn_context_markdown(loopx/presentation/renderers/turn_envelope_markdown.py:47-49):改写为 "# LoopX Turn Envelope\n\n" + render_json_object_block(payload),经直接探针验证对正常 loopx_turn_envelope_v1 与组合拒绝载荷均产出与基线一致的 Markdown 与 JSON 解析结果。

对主干的风险 / Risks

未发现 P0/P1/P2 阻塞问题;作用域、兼容性与验证归因分析如下:

  • 调用方与正反边界验证:scope_fit 检查确认 _quota_renderer 在生产代码由 quota_result_delivery.py 直接调用,skills/loopx-self-repair/references/repair-patterns.md 属按需检索参考表而非默认自动注入根指令,未引入隐式默认行为改变(default_off_isolation 不适用:本修复无 opt-in 开关;authority_semantics 与 semantic_alignment 均对齐,未新增状态枚举、协议版本或词表项)。反向边界探针确认:在基线 8e9a28a866 上执行 loopx --format markdown ... quota should-run --goal-id missing-goal --agent-id invalid/agent(exit 1)误输出 # LoopX Turn Envelope,而在 PR head 3aece4651e 上同命令同退出码正确输出 # LoopX Quota Should Run 与 - ok: False`` 并完整保留 --format json 全部 14 个字段(仅单次调用生成的 `event_id` 与 `recorded_at` 不同)。另注意 `ok=True` 且无 `COMPLETE_TURN_DECISION_VERSION` 的 `--scheduler-observation` / `--prepared-capture-reference` 在 `failure=False` 下沿用既有的 `render_turn_context_markdown` 路径,属基线既有约定且未被本 PR 改变。
  • 验证矩阵与既有失败归因(exact head 3aece4651e6a5b89699f6be554c493ad1d0eb5dc):
    • 核心权限/捕获/边界/信封/导入边界 pytest(5 套件):PASS — 193 passed in 60.96s。
    • 展示与 CLI 投影/差异化 pytest(5 套件:test_operator_markdown_renderers.py、test_quota_markdown_boundary.py、test_quota_markdown_renderers.py、test_quota_cli_projection.py、test_cli_output_differential.py):PASS — 307 passed, 1 skipped in 21.78s(仅 pwsh 未安装跳过 1 项 Windows PowerShell 测试)及直接渲染探针全部通过。
    • tests/control_plane/test_cli_output_budget.py:FAIL (pre_existing_unrelated) — 10 项断言失败(如 test_quota_should_run_no_format_uses_machine_contract_json 期望 # LoopX Quota Should Run 等早先旧格式契约),经在未改动的合入基线 8e9a28a866 同参数复跑确认完全同因同签名复现(10 failed, 1 passed),且均位于 exit_code == 0 的 failure=False 路径,不受本 PR 修改影响。
    • examples/control_plane/cli-output-budget-regression-smoke.py(含 cli-output-base-head-differential-smoke.py):PASS — cli-output-budget-regression-smoke ok。
    • ruff check(全部 6 个修改的 Python 文件)与 mypy --follow-imports=silent(4 个修改的生产 Python 文件):PASS — 0 问题(不带 --follow-imports=silent 时 mypy 在 463 个未修改导入文件中报出 4,490 个既有关联错误)。
    • loopx check --scan-path ...(7 文件公私边界扫描)、scripts/check_rfc_bilingual.py、git diff --check、py_compile、control-plane-maintainability-ratchet-smoke.py、quota-scheduler-state-ack-smoke.py:PASS。
    • canary premerge --tier quick 中的 examples/semantic-vocabulary-drift-smoke.py:FAIL (external_unrelated / worktree 缺 npm dev 依赖) — 因隔离复核 worktree 未安装 typescript npm 包抛出 ValueError,本 PR 经检查 diff 确认未增改任何枚举、Literal 或词表条目。
    • 远端 GitHub CI:按 Goal 配置 wait_for_ci=false(ci_policy=not_consulted),未依赖也未等待远端 CI(UNVERIFIED)。

我的整体评价 / Verdict

  • Long-horizon 影响:improved — 消除 quota should-run 未完成失败在 Markdown 通道伪装成 Turn Envelope 的误导信号,保证失败后读取到的恢复指令、回执与 capture 引用保持可信,利于长程恢复与自修复闭环。
  • User-experience 影响:improved — 对直接排查 CLI Markdown 输出的用户与宿主工具,明确区分 # LoopX Quota Should Run(- ok: False``)失败诊断与 # LoopX Turn Envelope 已组合结果,同时完整保留排障所需的 JSON 载荷。(`visual_review` 为 `not_applicable`:仅修改 CLI Markdown 文本渲染与参考文档,无 GUI/网页渲染视图变更;`unverified_scope`: `none`)。
  • 可观测语义 / 代码体积 / 词表边界:observable_semantics 为 intentional_change_validated(修复未形成 loopx_turn_envelope_v1 的失败分派标题错位,同时已验证 loopx_turn_envelope_v1 合规拒绝与 ok=True 路径输出不变);code_volume 为 necessary(compatibility_assessment: retain,提取共享 render_json_object_block 避免双份 JSON 块格式化逻辑,保持旧函数签名与 JSON 输出不变);change_proportionality 为 proportionate(architecture_assessment: retain);default_off_isolation 与 authority_semantics 均为 not_applicable(无特性开关、actor 生命周期或权限模型变更);semantic_alignment 为 aligned(candidate_decision="reuse_existing",未新增或修改任何状态词表与注册表条目)。
  • 剩余风险与合入状态:本地验证覆盖单测、差异化冒烟、真实 CLI 正反对比与静态检查;唯一环境限制是隔离 worktree 未装 npm typescript 导致 TS 词表扫描脚本未运行(已人工确认无词表改动),且主干 merge_state 为 BEHIND、存在旧 test_cli_output_budget.py 基线红项与待独立合并门禁检查。按本次任务约束发布审查结论后保持 PR #9112 为 OPEN。

English verdict: APPROVE exact head 3aece46 (author-owned COMMENTED approval review); routes incomplete quota should-run failures to # LoopX Quota Should Run diagnostics while preserving # LoopX Turn Envelope for composed v1 refusals and extracting shared render_json_object_block, verified by 193 core permission/capture tests, 307 presentation/projection tests, cli-output-budget-regression-smoke, ruff, follow-imports-silent mypy, public boundary scan, and base/head CLI failure counterfactuals (with pre-existing test_cli_output_budget.py assertions reproduced identically on merge-base 8e9a28a).

@mergify

mergify Bot commented Nov 21, 2026

Copy link
Copy Markdown

This pull request has merge conflicts with main and cannot be merged
until they are resolved. Please rebase or merge the base branch, @loopx-agent.

Choose the remote for the base repository, not an out-of-date fork.
For a fork clone, first inspect git remote -v; upstream must point
to https://github.com/loopx-project/loopx.git. If it is absent, add it
with git remote add upstream https://github.com/loopx-project/loopx.git.
Then run:

git fetch upstream
git rebase upstream/main
# Resolve each conflict, git add the resolved files, then git rebase --continue.
git push --force-with-lease origin HEAD

For a same-repository clone whose origin points to
https://github.com/loopx-project/loopx.git, use origin instead of
upstream for fetch/rebase. If you prefer merging the base, use
git merge <base-remote>/main and push normally.

Keep the DCO Signed-off-by trailer on every commit when you rebase.
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

@mergify mergify Bot added the needs-rebase Mergify: the pull request has merge conflicts with its base branch label Nov 21, 2026

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · gpt-6.2-sol · OpenAI (runtime_reported, xhigh)

Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

动机 / Motivation

从 quota should-run 的 Markdown 输出判断是否已形成可继续使用的工作决定的 CLI 用户和宿主。 权限不足或 capture 参数不合法时,命令没有生成完整 Turn,却显示 LoopX Turn Envelope,用户需要读入正文才能分辨回执状态。 未生成完整决定的失败现在显示 LoopX Quota Should Run 和明确的失败状态。原诊断、回执及可用的恢复引用仍在原 JSON 块里。已生成的完整决定继续显示 LoopX Turn Envelope。 验证覆盖源码 CLI、隔离 File 和 SQLite、真实本地 Core。权限拒绝和中断用例使用故障注入。正式安装宿主与托管 CI 未验证。 PR 在当前主干有一处测试文件文本冲突,作者需要把保留完整诊断的断言带入最新主干。

改动思路 / Approach

在现有 Markdown dispatcher 按完整决定的 schema 区分两类输出,复用 JSON 块格式。 实际改动边界在 loopx/cli_commands/quota_presentation.py。承载完整决策的正文以及失败诊断都沿用同一个 JSON 块格式。配额和调度决策继续由既有 Core 负责,renderer 只读决策返回值。 路由 共享输出 原诊断捕获

具体改动 / Changes

精确头 3aece46,以 8e9a28a 为基线,7 个文件新增 62 行、删除 18 行。

  • diagnostic-markdown。直接运行真实 CLI,选取无有效 Turn 的 capture 参数得到退出码 1。File 与 SQLite 下,Markdown 改为明确的失败诊断。两种格式跨版本保留同一组 13 个字段,比较时仅剔除 rollout 事件的实例 ID 和时间。 诊断渲染
  • complete-turn-parity。真实零额度决定仍为完整 Turn,正文保留 throttled_skip,两个后端额度均为零次扣减。定向 renderer 用例也确认 ok=false 的完整载体仍保留原决定标题。 完整决定渲染 组成拒绝用例

对主干的风险 / Risks

在主干 717924d 上复现同一个旧标题。精确头和仅调和测试断言后的本地整合树都通过 116 项,整合树另有 48 项配额输出及差分预算用例通过。前一组覆盖权限拒绝、原诊断、已写 capture 和摘要读回。主干更新到 790f3a4 后,重新验证同一整合方式,21 项定向用例通过。Git 内容冲突仍限定在一处测试的旧标题断言。整合对照保留主干其他测试,并采用当前补丁对退出码和可解析 JSON 的断言。若宿主以前依赖错误标题,应以 JSON 的既有状态字段判断完整决定。 冲突位置 新的读回断言

我的整体评价 / Verdict

APPROVE。 未发现阻塞当前代码行为的问题。CLI 在失败时能直接提示恢复,并保留真实完整决策的原读取路径。当前测试冲突仍阻止直接合并,解决后需对新头做精确核验。验证覆盖源码 CLI、隔离 File 和 SQLite、真实本地 Core。权限拒绝和中断用例使用故障注入。正式安装宿主与托管 CI 未验证。

English verdict: APPROVE at 3aece46. Real CLI results across both stores confirm distinct diagnostics for incomplete failures and preservation of complete refusals, original payload fields and quota behavior. The current-main test conflict still blocks merge.

@loopx-agent
loopx-agent merged commit 0a0c2a7 into main Nov 21, 2026
8 of 11 checks passed
@loopx-agent
loopx-agent deleted the codex/preserve-quota-guard-markdown-diagnostics-20261120 branch November 21, 2026 15:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-rebase Mergify: the pull request has merge conflicts with its base branch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant